
                The Amazing Address Book Demonstration Program
                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

                      Muse Version Modules documentation
                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Introduction
~~~~~~~~~~~~
   In this document I will describe the two modules used by the Muse version.
Specifically the `address.e' and `address_gui.e' files.

Address_gui.e Module
--------------------
   This module deals with all interaction between the application and the
interface, dealing with appearance. The `processing' of it is handled by the
address.e file. This module defines all the event numbers as used by the main file
via an enumeration.

   The procedure address_book_window() just returns a pointer to the window
definition declared after the IS part of the procedure header. Since the image
gadgets in the window are used just for generating events, they are given events
to raise, but not given virtual variable names. Whereas the string gadgets _are_
used as virtual variables, but are not used for events generation so they are
given names, and null-event numbers (zero).

   The procedure display_person() uses the string gadgets to display a person
inside, and as such needs to use the gadget handle to use the procedure
set_gadgetinfo. The line
             FOR f:=0 TO 7 DO set_gadgetinfo(gads[f], t[f])
has got a couple of optimisations in it.

   Firstly, it uses an array created by init_gads() that is a list of gadget
pointers to the string gadgets to avoid having to use the procedure
get_gadgethandle(name) over and over since this would involve _potentially_ up to
36 string comparisons per person.

   Secondly the fact that they're in an array in the same order as the fields
they refer to in the flat file form that is returned by a person's 'flat()'
method allows us to use the FOR loop.

   The procedure get_person() dynamically allocates space for a list of the fields
currently enters. Uses the `gads' array to cycle through the gadgets, creating
_copies_ of the data stored, and places a pointer to the data in the appropriate
position in the array `t'. This is then used to create a new person. The array is
then disposed of, and the pointer to the person returned.

   Hopefully the procedure init_gads() should be understandable. If it isn't,
try adding the line WriteF('\s\n', gad_labels[f]) into the FOR loop to see better
what's happening!

The procedure copy_str(str) is used to create a pointer to a copy of str.
The procedure clear_display() cycle's through all the gadgets setting their
contents to ''.


Address.e File
--------------
   This does the difficult bit of binding all the other files together into one
(coherant?) system. The procedure main() is a stub really that sets Muse going
with an interface definition returned by the procedure address_book() that it
itself uses the pointer returned by address_book_window() (from the module above)
and the pointer returned by the procedure `processing()'.

   The procedure `processing()' takes all the EVENTS as defined in the gui module,
and uses them to map to a processing procedure as per normal.

   display_greetings() is called by Muse once the display has been opened. It
initialises the gui module with respect to the `gads' variable. It initialises
the people module. Creates a person with a message stored in it, displays it and
erases the person.

Bizarrely, the remaining procedures are self-explainatory. (!)
This module looks almost like pseudo-code for a program, but its is in fact
concrete level actual code. Personally, I think that's good since it makes
checking the code that much easier!


Comment
~~~~~~~
  This is a very simple, but robust and readable example, (I feel) of a quarter top
half decent program. I hope it demonstrates some good techniques for programming,
but it's main use is to show the difference between it and the CLI/text version.

   The things this program is lacking is better searching support, load/save
abilities, better control of the searching - eg a separate window for entry of
search parameters, a window for data entry, and a window for display of results,
but the hearts in the right place. It would also be nice to see an ARexx port
added to the program! (maybe a modified version of the text version?...)
